package com.expert.miniapp.service;

import com.expert.miniapp.dao.Demand;
import com.expert.miniapp.dto.DemandDTO;
import com.expert.miniapp.dto.DemandHistoryDTO;
import com.expert.miniapp.dto.RecommendationResponseDTO;
import com.github.pagehelper.PageInfo;

import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * DemandService - 需求服务接口
 *
 * @author System
 * @since 2025-10-19
 */
public interface DemandService {

    /**
     * 创建新需求（状态默认为DRAFT）
     *
     * @param demandDTO 需求DTO对象
     * @return 创建后的需求对象
     */
    Demand createDemand(DemandDTO demandDTO);

    /**
     * 更新需求信息
     *
     * @param demandId  需求ID
     * @param demandDTO 需求DTO对象
     * @return 更新后的需求对象
     */
    Demand updateDemand(String demandId, DemandDTO demandDTO);

    /**
     * 提交需求（状态从DRAFT变更为SUBMITTED）
     *
     * @param demandId 需求ID
     * @return 提交后的需求对象
     */
    Demand submitDemand(String demandId);

    /**
     * 根据需求ID获取需求详情
     *
     * @param demandId 需求ID
     * @return 需求对象，如果不存在则返回null
     */
    Demand getDemandById(String demandId);

    /**
     * 根据用户ID获取需求列表
     *
     * @param userId 用户ID
     * @return 需求列表
     */
    PageInfo<Demand> getDemandsByUserId(String userId, int pageNum, int pageSize);

    /**
     * 获取所有需求列表
     *
     * @return 需求列表
     */
    List<Demand> getAllDemands();

    /**
     * 删除需求（级联删除所有推荐记录）
     *
     * @param demandId 需求ID
     * @return 删除结果信息（删除的记录数）
     */
    Map<String, Integer> deleteByIdCascade(String demandId);

    /**
     * 获取用户需求历史记录列表（带分页和时间筛选）
     *
     * @param userId    用户ID
     * @param pageNum   页码
     * @param pageSize  每页大小
     * @param startTime 开始时间（可选）
     * @param endTime   结束时间（可选）
     * @return 分页结果
     */
    PageInfo<DemandHistoryDTO> getUserDemandsWithPagination(
        String userId,
        Integer pageNum,
        Integer pageSize,
        LocalDateTime startTime,
        LocalDateTime endTime
    );

    /**
     * 获取需求完整详情（包含需求信息和推荐记录）
     *
     * @param demandId 需求ID
     * @return 完整详情Map（demand + recommendations）
     */
    Map<String, Object> getDemandComplete(String demandId);

    /**
     * 运行AI智能匹配并持久化推荐与明细。
     *
     * @param demandId 需求ID
     * @return 推荐结果响应DTO
     */
    RecommendationResponseDTO runAIMatchAndPersist(String demandId);

    /**
     * 重新生成需求的AI摘要
     *
     * 调用AI API为指定需求重新生成摘要，更新summary字段
     * 适用于需要刷新摘要或初始生成失败的场景
     *
     * @param demandId 需求ID
     * @return 更新后的需求对象（包含新生成的summary）
     * @throws IllegalArgumentException 如果需求不存在
     * @throws RuntimeException 如果AI生成摘要失败
     */
    Demand regenerateDemandSummary(String demandId);
}
